Crate cbor

Source
Expand description

This crate provides an implementation of RFC 7049, which specifies Concise Binary Object Representation (CBOR). CBOR adopts and modestly builds on the data model used by JSON, except the encoding is in binary form. Its primary goals include a balance of implementation size, message size and extensibility.

The implementation here is mostly complete. It includes a mechanism for serializing and deserializing your own tags, but it does not yet support indefinite length encoding.

This library is primarily used with type-based encoding and decoding via the rustc-serialize infrastructure, but the raw CBOR abstract syntax is exposed for use cases that call for it.

§Example: simple type based encoding and decoding

In this crate, there is a Decoder and an Encoder. All reading and writing of CBOR must go through one of these types.

The following shows how use those types to encode and decode a sequence of data items:

use cbor::{Decoder, Encoder};

// The data we want to encode. Each element in the list is encoded as its own
// separate top-level data item.
let data = vec![(s("a"), 1), (s("b"), 2), (s("c"), 3)];

// Create an in memory encoder. Use `Encoder::from_writer` to write to anything
// that implements `Writer`.
let mut e = Encoder::from_memory();
e.encode(&data).unwrap();

// Create an in memory decoder. Use `Decoder::from_reader` to read from
// anything that implements `Reader`.
let mut d = Decoder::from_bytes(e.as_bytes());
let items: Vec<(String, i32)> = d.decode().collect::<Result<_, _>>().unwrap();

assert_eq!(items, data);

§Example: encode and decode custom tags

This example shows how to encode and decode a custom data type as a CBOR tag:

use cbor::CborTagEncode;
use rustc_serialize::{Decodable, Decoder, Encodable, Encoder};

struct MyDataStructure {
    data: Vec<u32>,
}

impl Encodable for MyDataStructure {
    fn encode<E: Encoder>(&self, e: &mut E) -> Result<(), E::Error> {
        // See a list of tags here:
        // http://www.iana.org/assignments/cbor-tags/cbor-tags.xhtml
        //
        // It is OK to choose your own tag number, but it's probably
        // best to choose one that is unassigned in the IANA registry.
        CborTagEncode::new(100_000, &self.data).encode(e)
    }
}

// Note that the special type `CborTagEncode` isn't needed when decoding. You
// can decode into your `MyDataStructure` type directly:
impl Decodable for MyDataStructure {
    fn decode<D: Decoder>(d: &mut D) -> Result<MyDataStructure, D::Error> {
        // Read the tag number and throw it away. YOU MUST DO THIS!
        try!(d.read_u64());
        // The *next* data item is the actual data.
        Ok(MyDataStructure { data: try!(Decodable::decode(d)) })
    }
}

Any value with type MyDataStructure can now be used the encoding and decoding methods used in the first example.

§Example: convert to JSON

Converting to JSON is simple because Cbor implements the ToJson trait:

use cbor::{Decoder, Encoder};
use rustc_serialize::json::{Json, ToJson};

let mut e = Encoder::from_memory();
e.encode(&[vec![(true, (), 1), (false, (), 2)]]).unwrap();

let mut d = Decoder::from_bytes(e.as_bytes());
let cbor = d.items().next().unwrap().unwrap();

assert_eq!(cbor.to_json(), Json::Array(vec![
    Json::Array(vec![Json::Boolean(true), Json::Null, Json::U64(1)]),
    Json::Array(vec![Json::Boolean(false), Json::Null, Json::U64(2)]),
]));

This crate also defines a ToCbor trait and implements it for the Json type, so you can convert JSON to CBOR in a similar manner as above.

Structs§

  • CborBytes
    A byte string (major type 2).
  • CborTag
    A tag (major type 6).
  • CborTagEncode
    A special type that can be used to encode CBOR tags.
  • DecodedItems
    An iterator over items decoded from CBOR into Rust values.
  • Decoder
    Read CBOR data items into Rust values from the underlying reader R.
  • DirectDecoder
    Experimental and incomplete direct decoder.
  • Encoder
    Encodes Rust values to CBOR bytes in the underlying writer W.
  • Items
    An iterator over CBOR items in terms of the abstract syntax.

Enums§

  • Cbor
    CBOR abstract syntax.
  • CborError
    Errors that can be produced by a CBOR operation.
  • CborFloat
    An IEEE 754 floating point number (major type 7).
  • CborSigned
    A negative integer (major type 1).
  • CborUnsigned
    An unsigned integer (major type 0).
  • ReadError
    An error produced by reading CBOR data.
  • Type
    All core types defined in the CBOR specification.
  • WriteError
    An error produced by writing CBOR data.

Traits§

  • ToCbor
    A trait for converting values to CBOR.

Type Aliases§